<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>dnaupd</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function  </center>
    <div align="right">Last update : 31/10/2006</div>
    <p>
      <b>dnaupd</b> - Interface for the Implicitly Restarted Arnoldi Iteration,  to compute approximations to a 
few eigenpairs of a real linear operator </p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt>[IDO,RESID,V,IPARAM,IPNTR,WORKD,WORKL,INFO] = dsaupd(ID0,BMAT,N,WHICH,NEV,TOL,RESID,NCV,V,IPARAM,IPNTR,WORKD,WORKL,INFO)</tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Parameters</font>
    </h3>
    <ul>
      <li>
        <tt>
          <b>ID0</b>
        </tt>
        <p>
       : Integer.  (INPUT/OUTPUT) Reverse communication flag.  IDO must be zero on the first 
          call to dnaupd.  IDO will be set internally to
          indicate the type of operation to be performed.  Control is
          then given back to the calling routine which has the
          responsibility to carry out the requested operation and call
          dnaupd with the result.  The operand is given in
          WORKD(IPNTR(1)), the result must be put in WORKD(IPNTR(2)).
	  </p>
        <p> 
	    IDO =  0: first call to the reverse communication interface
	  </p>
        <p> 
	    IDO = -1: compute  Y = OP * X  where
	    IPNTR(1) is the pointer into WORKD for X,
	    IPNTR(2) is the pointer into WORKD for Y.
	    This is for the initialization phase to force the
	    starting vector into the range of OP.
	  </p>
        <p> 
	    IDO =  1: compute  Y = OP * X  where
                    IPNTR(1) is the pointer into WORKD for X,
                    IPNTR(2) is the pointer into WORKD for Y.
                    In mode 3 and 4, the vector B * X is already
                    available in WORKD(ipntr(3)).  It does not
                    need to be recomputed in forming OP * X.
	  </p>
        <p> 
	    IDO =  2: compute  Y = B * X  where
                    IPNTR(1) is the pointer into WORKD for X,
                    IPNTR(2) is the pointer into WORKD for Y.
	  </p>
        <p> 
	    IDO =  3: compute the IPARAM(8) real and imaginary parts 
                    of the shifts where INPTR(14) is the pointer
                    into WORKL for placing the shifts. See Remark
                    5 below.
	  </p>
        <p> 
	    IDO = 99: done
	  </p>
      </li>
      <li>
        <tt>
          <b>BMAT</b>
        </tt>
	    : Character, specifies the type of the matrix B that defines the
	    semi-inner product for the operator OP.
	  <p> 
	    B = 'I' -&gt; standard eigenvalue problem A*x = lambda*x
	  </p>
        <p> 
	    B = 'G' -&gt; generalized eigenvalue problem A*x = lambda*B*x
	  </p>
      </li>
      <li>
        <tt>
          <b>N</b>
        </tt>
       : Integer, dimension of the eigenproblem.
       </li>
      <li>
        <tt>
          <b>WHICH</b>
        </tt>
	    : string of length 2, Specify which of the Ritz values of OP to compute.
	  <p>
	     'LM' - want the NEV eigenvalues of largest magnitude.
	  </p>
        <p> 
	    'SM' - want the NEV eigenvalues of smallest magnitude.
	  </p>
        <p> 
	    'LR' - want the NEV eigenvalues of largest real part.
	  </p>
        <p> 
	    'SR' - want the NEV eigenvalues of smallest real part.
	  </p>
        <p> 
	    'LI' - want the NEV eigenvalues of largest imaginary part.
	  </p>
        <p> 
	    'SI' - want the NEV eigenvalues of smallest imaginary part.
	  </p>
      </li>
      <li>
        <tt>
          <b>NEV</b>
        </tt>
       : Integer, number of eigenvalues of OP to be computed. 0 &lt; NEV  &lt; N-1.
       </li>
      <li>
        <tt>
          <b>TOL</b>
        </tt>
       : scalar.   Stopping criterion: the relative accuracy of the Ritz value 
	    is considered acceptable if BOUNDS(I) &lt;= TOL*ABS(RITZ(I)).
	    If TOL &lt;= 0. is passed the machine precision is set.
       </li>
      <li>
        <tt>
          <b>RESID</b>
        </tt>
	    : array of length N (INPUT/OUTPUT)
	  <p>
	    On INPUT: 
	    If INFO==0, a random initial residual vector is used, else RESID contains the initial residual vector,
                possibly from a previous run.
	  </p>
        <p>
	    On OUTPUT:
	    RESID contains the final residual vector. 
	  </p>
      </li>
      <li>
        <tt>
          <b>NCV</b>
        </tt>
       : Integer.  Number of columns of the matrix V. NCV must satisfy the two
          inequalities 2 &lt;= NCV-NEV and NCV &lt;= N.
          This will indicate how many Arnoldi vectors are generated 
          at each iteration.  After the startup phase in which NEV 
          Arnoldi vectors are generated, the algorithm generates 
          approximately NCV-NEV Arnoldi vectors at each subsequent update 
          iteration. Most of the cost in generating each Arnoldi vector is 
          in the matrix-vector operation OP*x. 
	  <p>
          NOTE: 2 &lt;= NCV-NEV in order that complex conjugate pairs of Ritz 
          values are kept together. (See remark 4 below)
	  </p>
      </li>
      <li>
        <tt>
          <b>V</b>
        </tt>
       : N by NCV array. Contains the final set of Arnoldi basis vectors. 
       </li>
      <li>
        <tt>
          <b>IPARAM</b>
        </tt>
       : array of length 11.  (INPUT/OUTPUT)
	  <p>
          IPARAM(1) = ISHIFT: method for selecting the implicit shifts.
          The shifts selected at each iteration are used to restart
          the Arnoldi iteration in an implicit fashion.
	  </p>
        <p>

          ISHIFT = 0: the shifts are provided by the user via
                      reverse communication.  The real and imaginary
                      parts of the NCV eigenvalues of the Hessenberg
                      matrix H are returned in the part of the WORKL 
                      array corresponding to RITZR and RITZI. See remark 
                      5 below.
	  </p>
        <p>
          ISHIFT = 1: exact shifts with respect to the current
                      Hessenberg matrix H.  This is equivalent to 
                      restarting the iteration with a starting vector
                      that is a linear combination of approximate Schur
                      vectors associated with the "wanted" Ritz values.
	  </p>
        <p>
          IPARAM(2) = LEVEC
          No longer referenced. 
	  </p>
        <p>
          IPARAM(3) = MXITER
          On INPUT:  maximum number of Arnoldi update iterations allowed. 
          On OUTPUT: actual number of Arnoldi update iterations taken. 
	  </p>
        <p>
          IPARAM(4) = NB: blocksize to be used in the recurrence.
          The code currently works only for NB = 1.
	  </p>
        <p>
          IPARAM(5) = NCONV: number of "converged" Ritz values.
          This represents the number of Ritz values that satisfy
          the convergence criterion.
	  </p>
        <p>
          IPARAM(6) = IUPD
          No longer referenced. Implicit restarting is ALWAYS used. 
	  </p>
        <p>
          IPARAM(7) = MODE
          On INPUT determines what type of eigenproblem is being solved.
          Must be 1,2,3,4; See under Description of dsaupd  for the 
          five modes available.
	  </p>
        <p>
          IPARAM(8) = NP
          When ido = 3 and the user provides shifts through reverse
          communication (IPARAM(1)=0), dsaupd  returns NP, the number
          of shifts the user is to provide. 0  &lt; NP  &lt;= NCV-NEV. See Remark
          5 below.
	  </p>
        <p>
          IPARAM(9) = NUMOP, IPARAM(10) = NUMOPB, IPARAM(11) = NUMREO,
          OUTPUT: NUMOP  = total number of OP*x operations,
                  NUMOPB = total number of B*x operations if BMAT='G',
                  NUMREO = total number of steps of re-orthogonalization.        

	  </p>
      </li>
      <li>
        <tt>
          <b>IPNTR</b>
        </tt>
	    : array of length 14.  Pointer to mark the starting locations in the WORKD and WORKL
	    arrays for matrices/vectors used by the  Arnoldi iteration.
	  <p>
	    IPNTR(1): pointer to the current operand vector X in WORKD.
	  </p>
        <p>
	    IPNTR(2): pointer to the current result vector Y in WORKD.
	  </p>
        <p>
	    IPNTR(3): pointer to the vector B * X in WORKD when used in 
	    the shift-and-invert mode.
	  </p>
        <p>
	    IPNTR(4): pointer to the next available location in WORKL
	    that is untouched by the program.
	  </p>
        <p>
	    IPNTR(5):  pointer to the NCV by NCV upper Hessenberg matrix
                    H in WORKL.
	  </p>
        <p>
	    IPNTR(6): pointer to the real part of the ritz value array 
                    RITZR in WORKL.
	  </p>
        <p>
	    IPNTR(7): pointer to the imaginary part of the ritz value array
                    RITZI in WORKL.
	  </p>
        <p>
	    IPNTR(8): pointer to the Ritz estimates in array WORKL associated
                    with the Ritz values located in RITZR and RITZI in WORKL.
	  </p>
        <p>
	    IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 below.
	  </p>
        <p>
	    Note: IPNTR(9:13) is only referenced by dseupd . See Remark 2.
	  </p>
        <p>
	    IPNTR(9): pointer to the real part of the NCV RITZ values of the 
                     original system.
	  </p>
        <p>
	    IPNTR(10): pointer to the imaginary part of the NCV RITZ values of 
                     the original system.
	  </p>
        <p>
	    IPNTR(11): pointer to the NCV corresponding error bounds.
	  </p>
        <p>
	    IPNTR(12):pointer to the NCV by NCV upper quasi-triangular
                     Schur matrix for H.
	  </p>
        <p>
	    IPNTR(11): pointer to the NCV by NCV matrix of eigenvectors
                     of the upper Hessenberg matrix H. Only referenced by
                     dneupd if RVEC = .TRUE. See Remark 2 below.
	  </p>
      </li>
      <li>
        <tt>
          <b>WORKD</b>
        </tt>
       : Double precision work array of length 3*N.  (REVERSE COMMUNICATION)
          Distributed array to be used in the basic Arnoldi iteration
          for reverse communication.  The user should not use WORKD 
          as temporary workspace during the iteration. Upon termination
          WORKD(1:N) contains B*RESID(1:N). If an invariant subspace
          associated with the converged Ritz values is desired, see remark
          2 below, subroutine dneupd uses this output.
          See Data Distribution Note below. 
       </li>
      <li>
        <tt>
          <b>WORKL</b>
        </tt>
       : work array of length at least 3*NCV**2 + 6*NCV.  (OUTPUT/WORKSPACE)
         Private (replicated) array on each PE or array allocated on
          the front end.  See Data Distribution Note below.
       </li>
      <li>
        <tt>
          <b>INFO</b>
        </tt>
       : Integer.  (INPUT/OUTPUT)
	  <p>
         If INFO == 0, a randomly initial residual vector is used, else RESID contains the initial residual vector,
                         possibly from a previous run.
	  </p>
        <p>
         Error flag on output.
	  </p>
        <p>
         =  0: Normal exit.
          </p>
        <p>
         =  1: Maximum number of iterations taken.
               All possible eigenvalues of OP has been found. IPARAM(5)  
               returns the number of wanted converged Ritz values.
          </p>
        <p>
         =  2: No longer an informational error. Deprecated starting
               with release 2 of ARPACK.
          </p>
        <p>
         =  3: No shifts could be applied during a cycle of the 
               Implicitly restarted Arnoldi iteration. One possibility 
               is to increase the size of NCV relative to NEV. 
               See remark 4 below.
          </p>
        <p>
         = -1: N must be positive.
          </p>
        <p>
         = -2: NEV must be positive.
          </p>
        <p>
         = -3:  NCV-NEV &gt;= 2 and less than or equal to N.
          </p>
        <p>
         = -4: The maximum number of Arnoldi update iterations allowed
               must be greater than zero.
          </p>
        <p>
         = -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', 'SI'
          </p>
        <p>
         = -6: BMAT must be one of 'I' or 'G'.
          </p>
        <p>
         = -7: Length of private work array WORKL is not sufficient.
          </p>
        <p>
         = -8: Error return from LAPACK eigenvalue calculation;
          </p>
        <p>
         = -9: Starting vector is zero.
          </p>
        <p>
         = -10: IPARAM(7) must be 1,2,3,4.
          </p>
        <p>
         = -11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.
          </p>
        <p>
         = -12: IPARAM(1) must be equal to 0 or 1.
          </p>
        <p>
         = -9999: Could not build an Arnoldi factorization.
                  IPARAM(5) returns the size of the current Arnoldi
                  factorization. The user is advised to check that
                  enough workspace and array storage has been allocated.
	  </p>
      </li>
    </ul>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>
			Reverse communication interface for the Implicitly Restarted Arnoldi
			iteration. This subroutine computes approximations to a few eigenpairs 
			of a linear operator "OP" with respect to a semi-inner product defined by 
			a symmetric positive semi-definite real matrix B. B may be the identity 
			matrix. NOTE: If the linear operator "OP" is real and symmetric 
			with respect to the real positive semi-definite symmetric matrix B, 
			i.e. B*OP = (OP`)*B, then subroutine dsaupd should be used instead.   
		</p>
    <p>
			The computed approximate eigenvalues are called Ritz values and
			the corresponding approximate eigenvectors are called Ritz vectors.
		</p>
    <p>
			dnaupd is usually called iteratively to solve one of the 
			following problems:
		</p>
    <dl>
      <dd>
        <b></b>
        <p>
					Mode 1:  A*x = lambda*x. <tt>
            <b>OP = A , B = I</b>
          </tt>.
				</p>
      </dd>
      <dd>
        <b></b>
        <p>
					Mode 2:  A*x = lambda*M*x, M symmetric positive definite
					<tt>
            <b>OP = inv[M]*A,  B = M</b>
          </tt>.
					(If M can be factored see remark 3 below)
				</p>
      </dd>
      <dd>
        <b></b>
        <p>
					Mode 3:  A*x = lambda*M*x, M symmetric positive semi-definite.
					<tt>
            <b>OP = Real_Part{ inv[A - sigma*M]*M },   B = M</b>
          </tt>. 
					shift-and-invert mode (in real arithmetic)
					
					If <tt>
            <b>OP*x = amu*x</b>
          </tt>, then 
					<tt>
            <b>amu = 1/2 * [ 1/(lambda-sigma) + 1/(lambda-conjg(sigma))]</b>
          </tt>.
					
					Note: If sigma is real, i.e. imaginary part of sigma is zero;
					<tt>
            <b>Real_Part{ inv[A - sigma*M]*M } == inv[A - sigma*M]*M</b>
          </tt>
          <tt>
            <b>amu == 1/(lambda-sigma)</b>
          </tt>. 
				</p>
      </dd>
      <dd>
        <b></b>
        <p>
					Mode 4:  A*x = lambda*M*x, M symmetric semi-definite
					<tt>
            <b>OP = Imaginary_Part{ inv[A - sigma*M]*M }  ,  B = M</b>
          </tt>. 
					shift-and-invert mode (in real arithmetic)
					
					If <tt>
            <b>OP*x = amu*x</b>
          </tt>, then 
					<tt>
            <b>amu = 1/2i * [ 1/(lambda-sigma) - 1/(lambda-conjg(sigma)) ]</b>
          </tt>.
				</p>
      </dd>
    </dl>
			Both mode 3 and 4 give the same enhancement to eigenvalues close to
			the (complex) shift sigma.  However, as lambda goes to infinity,
			the operator OP in mode 4 dampens the eigenvalues more strongly than
			does OP defined in mode 3.
		<p>
			NOTE: The action of w &lt;- inv[A - sigma*M]*v or w &lt;- inv[M]*v
			should be accomplished either by a direct method
			using a sparse matrix factorization and solving
			
			<tt>
        <b>[A - sigma*M]*w = v</b>
      </tt>  or <tt>
        <b>M*w = v</b>
      </tt>,
			
			or through an iterative method for solving these
			systems.  If an iterative method is used, the
			convergence test must be more stringent than
			the accuracy requirements for the eigenvalue
			approximations.
		</p>
    <h3>
      <font color="blue">Remarks</font>
    </h3>
    <dl>
      <p>
			1. The computed Ritz values are approximate eigenvalues of OP. The
				selection of WHICH should be made with this in mind when
				Mode = 3 and 4.  After convergence, approximate eigenvalues of the
				original problem may be obtained with the ARPACK subroutine dneupd.
			
			2. If a basis for the invariant subspace corresponding to the converged Ritz 
				values is needed, the user must call dneupd immediately following 
				completion of dnaupd. This is new starting with release 2 of ARPACK. 
				
			3. If M can be factored into a Cholesky factorization M = LL`
				then Mode = 2 should not be selected.  Instead one should use
				Mode = 1 with  OP = inv(L)*A*inv(L`).  Appropriate triangular 
				linear systems should be solved with L and L` rather
				than computing inverses.  After convergence, an approximate
				eigenvector z of the original problem is recovered by solving
				L`z = x  where x is a Ritz vector of OP. 
				
			4. At present there is no a-priori analysis to guide the selection
				of NCV relative to NEV.  The only formal requrement is that NCV &gt; NEV + 2.
				However, it is recommended that NCV &gt;= 2*NEV+1.  If many problems of
				the same type are to be solved, one should experiment with increasing
				NCV while keeping NEV fixed for a given test problem.  This will 
				usually decrease the required number of OP*x operations but it
				also increases the work and storage required to maintain the orthogonal
				basis vectors.  The optimal "cross-over" with respect to CPU time
				is problem dependent and must be determined empirically. 
				See Chapter 8 of Reference 2 for further information. 
				
			5. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the 
				NP = IPARAM(8) real and imaginary parts of the shifts in locations 
		</p>
      <pre>

   real part                  imaginary part
   -----------------------    -----------------------
1  WORKL(IPNTR(14))           WORKL(IPNTR(14)+NP)
2  WORKL(IPNTR(14)+1)         WORKL(IPNTR(14)+NP+1)

NP  WORKL(IPNTR(14)+NP-1)     WORKL(IPNTR(14)+2*NP-1).

		</pre>
      <p>
			Only complex conjugate pairs of shifts may be applied and the pairs 
			must be placed in consecutive locations. The real part of the 
			eigenvalues of the current upper Hessenberg matrix are located in 
			WORKL(IPNTR(6)) through WORKL(IPNTR(6)+NCV-1) and the imaginary part 
			in WORKL(IPNTR(7)) through WORKL(IPNTR(7)+NCV-1). They are ordered
			according to the order defined by WHICH. The complex conjugate
			pairs are kept together and the associated Ritz estimates are located in
			WORKL(IPNTR(8)), WORKL(IPNTR(8)+1), ... , WORKL(IPNTR(8)+NCV-1). 
		</p>
    </dl>
    <h3>
      <font color="blue">See Also</font>
    </h3>
    <p>
      <a href="dsaupd.htm">
        <tt>
          <b>dsaupd</b>
        </tt>
      </a>,&nbsp;&nbsp;</p>
    <h3>
      <font color="blue">Authors</font>
    </h3>
    <dl>
      <dd>
        <b> Danny Sorensen, Richard Lehoucq, Phuong Vu </b>
    CRPC / Rice University  Applied Mathematics  Rice University           
    Houston, Texas   
    </dd>
    </dl>
    <h3>
      <font color="blue">Bibliography</font>
    </h3>
  1. D.C. Sorensen, "Implicit Application of Polynomial Filters in
     a k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992),
     pp 357-385.
<p>
  2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly 
     Restarted Arnoldi Iteration", Rice University Technical Report
     TR95-13, Department of Computational and Applied Mathematics.
</p>
    <p>
  3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall,
     1980.
</p>
    <p>
  4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos Program",
     Computer Physics Communications, 53 (1989), pp 169-179.
</p>
    <p>
  5. B. Nour-Omid, B.N. Parlett, T. Ericson, P.S. Jensen, "How to
     Implement the Spectral Transformation", Math. Comp., 48 (1987),
     pp 663-673.
</p>
    <p>
  6. R.G. Grimes, J.G. Lewis and H.D. Simon, "A Shifted Block Lanczos 
     Algorithm for Solving Sparse Symmetric Generalized Eigenproblems", 
     SIAM J. Matr. Anal. Apps.,  January (1993).
</p>
    <p>
  7. L. Reichel, W.B. Gragg, "Algorithm 686: FORTRAN Subroutines
     for Updating the QR decomposition", ACM TOMS, December 1990,
     Volume 16 Number 4, pp 369-377.
</p>
    <p>
  8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral
     Transformations in a k-Step Arnoldi Method". In Preparation.
</p>
    <h3>
      <font color="blue">Used Function</font>
    </h3>
      Based on ARPACK routine dsaupd
     </body>
</html>
